Inside Macintosh: Telephony /

Chapter 5 - Telephone Manager Messages

Handling Telephone Manager Messages

This section describes how to write and install message handlers.

Handling Messages

A message handler should be prepared to receive and handle any of the messages of the types specified when the handler was installed. (See the next section for details on installing a message handler.) As just indicated, a message handler is dedicated to handling either terminal, directory, or call appearance messages sent to the Telephone Manager by a telephone tool. A call appearance message handler, for instance, is declared like this:

pascal void MyCAMsgHandler (
                     TELCAHandle hTELCA,
                     long msg,
                     short mtype,
                     short value,
                     Ptr msgInfo,
                     long globals);

The values in the parameters are supplied by the Telephone Manager, which extracts most of them from a parameter block passed to it by the telephone tool. (See the chapter "Telephone Tools" for exact details on the many parameter blocks used by telephone tools.) The msg parameter specifies the message being sent to your handler, and the remaining parameters may contain additional information required to handle that message.

Listing 5-1 shows the skeleton of a call appearance message handler.

Listing 5-1 Handling call appearance messages

pascal void MyCAMsgHandler (TELCAHandle hTELCA, long msg, short mtype, 
                           short value, Ptr msgInfo, long ourA5)
{
   long  oldA5 = SetA5(ourA5);

   switch (msg) {
      case telCAAlertingMsg:
         MyHandleCAAlertingMsg(hTELCA, mtype, value, msgInfo);
         break;

      case telCAOfferMsg:
         MyHandleCAOfferMsg(hTELCA, mtype, value, msgInfo);
         break;

      //handle all other cases here

      default:
         ;
   }

   (void) SetA5(oldA5);
}

As you can see, the handler MyCAMsgHandler is essentially just a switch statement that dispatches to the appropriate function to handle each specific type of message.

Installing a Message Handler

To install a message handler, you call the TELTermMsgHand, TELDNMsgHand, or TELCAMsgHand function, depending on whether you want to install a terminal message handler, a directory number message handler, or a call appearance message handler. Listing 5-2 illustrates how to install a message handler to handle certain call appearance messages for a specified directory number.

Listing 5-2 Installing a call appearance message handler

TelephoneCAMsgUPPgCAMsgHandlerUPP;

TELErr MyInstallCAHandler (TELDNHandle dnHand)
{
   TELErrmyErr;
   long  myFlags;
   long  myGlobals;

   gCAMsgHandlerUPP = NewTelephoneCAMsgProc(MyCAMsgHandler);

   myFlags = telCAOtherMsg | telAllCAMsgs;
   myGlobals = SetCurrentA5();
   myErr = TELCAMsgHand(dnHand, myFlags, gCAMsgHandlerUPP, myGlobals);

   return(myErr);
}

The messages you want your handler to receive are specified by the second parameter to TELCAMsgHand (in this case, the myFlags parameter), a long integer whose bits encode message types. The value assigned to the myFlags parameter in Listing 5-2 requests that all call appearance messages be sent to the gCAMsgHandlerUPP message handler.

You can, if you like, install more than one message handler for a specific class of messages. For instance, you can install two or more handlers for call appearance messages. This can be useful to handle related sets of call appearance messages.